{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Collection of perceptually accurate colormaps\n",
    "\n",
    "[Colorcet](https://github.com/pyviz/colorcet) is a collection of \n",
    "perceptually acccurate 256-color colormaps for use with Python plotting programs like\n",
    "[Bokeh](http://bokeh.pydata.org),\n",
    "[Matplotlib](http://matplotlib.org),\n",
    "[HoloViews](http://holoviews.org), and\n",
    "[Datashader](https://github.com/pyviz/datashader). \n",
    "\n",
    "There are two types of colormaps currently included: [continuous](./user_guide/Continuous.ipynb) and [categorical](./user_guide/Categorical.ipynb). The continuous colormaps are perceptually uniform, with each new color equally perceptually distinct from the previous and following colors. The continuous maps were constructed by [Peter Kovesi](http://peterkovesi.com/projects/colourmaps) at the Center for Exploration Targeting using the methods described in [Kovesi (2015)](https://arxiv.org/abs/1509.03700).\n",
    "\n",
    "The [categorical](user_guide/Categorical.ipynb) colormaps are perceptually distinct, but not uniform; each color is meant for a separate category and not as a position on a numerical scale. Here, categorical colormaps of arbitrary length are generated to cover a perceptual space with well-separated samples, using the method from \n",
    "[Glasbey, van der Heijden, Toh, & Gray (2007)](https://strathprints.strath.ac.uk/30312/1/colorpaper_2006.pdf).\n",
    "\n",
    "See [Getting Started](http://colorcet.holoviz.org/getting_started) for installation info, and the [User Guide](./user_guide/index.ipynb) for more info on what colormaps are available and how to use them.\n",
    "\n",
    "\n",
    "## Background\n",
    "\n",
    "Apart from the four [uniform colormaps now provided with\n",
    "matplotlib](http://matplotlib.org/users/colormaps.html), most\n",
    "continuous colormaps shipping with Python plotting programs are highly\n",
    "perceptually nonuniform.  That is, small changes in data values\n",
    "result in large changes in the perceptual appearance of the\n",
    "corresponding colors, or vice versa.  For instance, the popular matplotlib\n",
    "\"hot\" and \"jet\" colormaps have long stretches where the apparent\n",
    "colors change imperceptibly, such as the yellow region in \"hot\" and\n",
    "the cyan/green region in \"jet\":\n",
    "\n",
    "![hot](assets/images/hot.png)    ![jet](assets/images/jet.png)\n",
    "\n",
    "When colormaps are used for visualizing scientific datasets, these\n",
    "perceptual nonlinearities can make interpretation of this data very\n",
    "difficult, because false boundaries appear in the data, and genuine\n",
    "boundaries and changes can be obscured.\n",
    "\n",
    "Matplotlib now offers a [tool to construct uniform\n",
    "colormaps](https://github.com/matplotlib/viscm), but it doesn't yet\n",
    "allow construction of colormaps like those above.  To address this\n",
    "need, Peter Kovesi at the Center for Exploration\n",
    "Targeting created a set of colormaps that are sampled uniformly in a\n",
    "perceptual color space, using methods he describes in a [paper on\n",
    "arXiv](https://arxiv.org/abs/1509.03700).  For instance, the\n",
    "perceptually uniform versions of the above colormaps are called \"fire\"\n",
    "and \"rainbow\" in this package:\n",
    "\n",
    "![fire](assets/images/fire.png)    ![rainbow](assets/images/rainbow.png)\n",
    "\n",
    "You should be able to see the differences right away, revealing more\n",
    "detail, more faithfully than if you use non-uniform maps.  For\n",
    "instance, here is a population-density dataset (from\n",
    "[datashader](https://github.com/bokeh/datashader)) rendered with the\n",
    "original matplotlib \"hot\" colormap:\n",
    "\n",
    "![census_hot](assets/images/census_hot.png)\n",
    "\n",
    "and the same dataset rendered with colorcet's \"fire\" colormap:\n",
    "\n",
    "![census_fire](assets/images/census_fire.png)\n",
    "\n",
    "It should be obvious that the \"hot\" version completely washes out\n",
    "detail at the high end, as if the image is overexposed, while \"fire\"\n",
    "makes detail visible throughout the data range.  Yet the qualitative\n",
    "effect is still roughly similar, allowing \"fire\" to be used in nearly\n",
    "any situation where the original \"hot\" was useful.\n",
    "\n",
    "Peter provides [versions of 50 perceptually uniform colormaps for a\n",
    "variety of different plotting programs](http://peterkovesi.com/projects/colourmaps), \n",
    "and this package provides those colormaps ready to use from within Python\n",
    "programs.  The colormaps are all illustrated in the \n",
    "[user guide](./user_guide/index.ipynb) that describes the \n",
    "different types available and allows you to test how perceptually\n",
    "uniform they are on your particular display device.\n",
    "\n",
    "Peter's methods differ from those used in Matplotlib's\n",
    "uniform colormaps (as implemented in their [viscm\n",
    "tool](https://github.com/matplotlib/viscm)), which (apart from using a\n",
    "different color model) are designed to satisfy different constraints.\n",
    "For instance, mpl's colormaps are always perceptually uniform in their\n",
    "monochrome representation, not just their original color\n",
    "representation, and are safe for colorblind viewers, neither of which\n",
    "are necessarily true of these colormaps.  On the other hand, colormaps\n",
    "like \"fire\" above, i.e., a usable perceptually equivalent of\n",
    "matplotlib/matlab's \"hot\", are not obtainable using viscm in any\n",
    "straightforward way, limiting the range of useful colormaps that can be created.\n",
    "In any case, this package focuses on making a set of useful colormaps\n",
    "readily available from within Python programs, rather than providing\n",
    "tools for building novel colormaps, for which see the \n",
    "[viscm tool](https://github.com/matplotlib/viscm) and\n",
    "[Peter's original site](http://peterkovesi.com/projects/colourmaps). \n",
    "\n",
    "Colorcet also includes [categorical colormaps](user_guide/Categorical.ipynb)\n",
    "that provide large numbers of distinct colors sampled systematically from a\n",
    "perceptually uniform space. These maps are made with similar methods, but \n",
    "with a goal of having recognizable different colors rather than showing \n",
    "an ordering like the perceptually uniform maps above.\n",
    "\n",
    "\n",
    "## Learning more\n",
    "\n",
    "You can see all the details about the methods used to create these\n",
    "colormaps in [Peter Kovesi (2015)](https://arxiv.org/pdf/1509.03700v1.pdf) and [Glasbey et al. (2007)](https://strathprints.strath.ac.uk/30312/1/colorpaper_2006.pdf).  Other useful\n",
    "background is available in a research paper from IBM\n",
    "[(Rogowitz & Treinish 1996)](https://github.com/ResearchComputing/USGS_2015_06_23-25/raw/master/25_June/ColorTheory_References/Why%20Should%20Engineers%20and%20Scientists%20Be%20Worried%20About%20Color.pdf).\n",
    "\n",
    "The Matplotlib project also has a number of relevant resources, including an excellent \n",
    "[2015 SciPy talk](https://www.youtube.com/watch?v=xAoljeRJ3lU), the\n",
    "[viscm tool for creating maps like the four in mpl](https://github.com/matplotlib/viscm), the\n",
    "[cmocean site](http://matplotlib.org/cmocean/) collecting a set of maps created by viscm, \n",
    "and the [discussion of how the mpl maps were created](https://bids.github.io/colormap/).\n",
    "\n",
    "## Samples\n",
    "\n",
    "All the colorcet colormaps that have short, memorable names (which are probably\n",
    "the most useful ones) are visible here:\n",
    "\n",
    "<img src=\"assets/images/named.png\" width=\"800\">\n",
    "\n",
    "But the complete set of 60+ is shown in the [User Guide](./user_guide/index.ipynb)."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
